docs: add v1 to v2 migration guide

[lntutor]

Description

Adds a living migration guide for applications moving from OpenMed v1 to v2. The guide documents compatibility guarantees, additive package namespaces, changed surfaces, the current deprecation path, and an upgrade verification checklist.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code refactoring
• Performance improvement
• Test addition/improvement

Changes Made

• Add the v1-to-v2 compatibility and migration guide.
• Add the guide to the MkDocs navigation.
• Link the guide from the README documentation index.

Testing

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have tested this change with different models/inputs

Commands run:

• uv run pytest tests/ -q: 5160 passed, 54 skipped
• uv run mkdocs build --strict
• Scoped pre-commit checks for the changed files

Documentation

• I have updated the documentation accordingly
• I have added docstrings to new functions/classes
• I have updated the CHANGELOG.md

Code Quality

• I ran make format, make lint, and make format-check
• For Swift/OpenMedKit changes, I ran make format-swift and make lint-swift
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings

Dependencies

• I have not added any new dependencies
• OR I have added new dependencies and they are justified because: ____

Checklist

• I have read the contributing guidelines
• My commits have clear, descriptive messages
• I have squashed/organized my commits appropriately

Related Issues

Closes #301

Screenshots/Examples

Not applicable; this is a documentation-only change.

[maziyarpanahi]

Thank you, @lntutor — this is a thoughtful and useful migration guide for people planning around v2. I added a small maintainer follow-up to make the version history exact: clinical and eval became public in 1.6.0, async FHIR Bulk landed in 1.8.0, and the newer structured flowsheet/lab-panel work is now clearly identified as post-1.9.1 v2 development rather than part of the 1.9.1 surface. The strict docs build passes, the focused v2/structured checks pass, the broad offline suite passed (5,197 tests on that review revision), and the refreshed hosted matrix is fully green across Linux, macOS, and Windows. This is ready to merge. Great contribution!