docs: add lots of comments

[jpoly1219]

Description

Closes CON-3748.

Add documentation for next edit codebase.

AI Code Review

• Team members only: AI review runs automatically when PR is opened or marked ready for review
• Team members can also trigger a review by commenting @continue-general-review or @continue-detailed-review

Checklist

• I've read the contributing guide
• The relevant docs, if any, have been updated or created
• The relevant tests, if any, have been updated or created

Screen recording or screenshot

[ When applicable, please include a short screen recording or screenshot - this makes it much easier for us as contributors to review and understand your changes. See this PR as a good example. ]

Tests

[ What tests were added or updated to ensure the changes work as expected? ]

---

Summary by cubic

Add developer-facing documentation across Next Edit and the VS Code extension to explain architecture, state flow (chains/jumps), and why prefetch/region-finding paths are currently unused. Addresses CON-3748 by making the Next Edit codebase easier to understand and maintain, with no behavior changes.

• Refactors
  • Removed unused _calculateOptimalEditableRegion and stale comments.
  • Clarified that prefetch queue and deterministic editable-region logic are not used; kept wrappers for potential future use.
  • Added clear entry-point notes, rendering flow, and toggling guidance for Next Edit (including where to enable/disable in tests).

[github-actions]

⚠️ AI review completed but no review output was generated. Check the action logs for details.

---

💡 To request a new review, comment @continue-general-review

[RomneyDa]

Helpful comments for next edit!

[sestinj]

🎉 This PR is included in version 1.13.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[sestinj]

🎉 This PR is included in version 1.12.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀