ENH: Add schema migration support for versioned resources

[GibranAlfa]

Resolves #249
Resolves #305

Most lines are documentation and tests.

Add automatic, forward-only schema migrations for project config, user config, and internal mappings.

• Load: Old data is migrated in memory. Loading does not change the stored file, create a cache revision, or add a changelog entry.
• Save: When the resource is next saved, the original JSON is preserved as a normal cache revision before the migrated data is written.
• Cache: Existing cache retention rules apply. Old cache revisions are migrated in memory when read.
• Restore: Old cache revisions are migrated to the current schema before they are restored. Restore keeps the existing changelog behavior.
• User experience: Migration happens automatically. Users do not need a separate endpoint or migration action.
• Added a backup for resources that require migration. The exact original JSON is saved under .fmu/migration-backups/, with timestamp, model name, and source schema version in the filename.. Backup failures are logged but do not block the save. Users can copy a backup manually when rolling back to an older release.
• Changed default cache_max_revisions from 5 to 10.

This also adds maintainer documentation and exports MigrationError from the public package API.

Related issue in fmu-settings-api is made to update the API to catch MigrationError properly.

Checklist

• Tests added (if not, comment why)
• Test coverage equal or up from main (run pytest with --cov=src/ --cov-report term-missing)
• If not squash merging, every commit passes tests
• Appropriate commit prefix and precise commit message used
• All debug prints and unnecessary comments removed
• Docstrings are correct and updated
• Documentation is updated, if necessary
• Latest main rebased/merged into branch
• Added comments on this PR where appropriate to help reviewers
• Moved issue status on project board
• Checked the boxes in this checklist ✅

[slangeveld]

Great work this and very nice that you have documented the migration process so well in the new README! A few comments and questions to discuss mainly on namings and structuring

[GibranAlfa]

Added a backup for resources that require migration. The exact original JSON is saved under .fmu/migration-backups/, with timestamp, model name, and source schema version in the filename. Backup failures are logged but do not block the save. Users can copy a backup manually when rolling back to an older release.

[slangeveld]

Since you change the behavior of the cache (changing max revisions from 5 to 10) in this PR, can you create an issue explaining why this has been done and reference it in the PR description?

Then we have it documented for later why we did this.

[GibranAlfa]

Yes, I just created the issue and resolved it in the PR desc.

[slangeveld]

Almost there 💪

[slangeveld]

Great work! Thanks for addressing all the comments