Improve documentation and readability of `calculate_subwatershed_boundary`

[emlys]

In trying to answer a routedem question (natcap/invest#2382), I was looking over the routing.calculate_subwatershed_boundary function and I found it pretty difficult to follow. I don't think anyone currently on the software team has an understanding of this algorithm. To improve maintainability and to be able to answer user questions, we should go through and add more explanatory comments. There also seem to be some nested conditionals, etc that could be simplified to make the code more readable.