docs: document customization save lifecycle and fix metered billing race

[darcszn]

Summary

• Document the customization studio save-state machine, debounce contract, and lifecycle in the hook JSDoc.
• Explain the autosave and manual save interaction, including why the delayed path posts the latest snapshot directly instead of calling the stale closure save function.
• Fix the lost-update race in metered usage recording by replacing the client-side read/then/update fallback with an atomic Postgres increment RPC.
• Add the migration and concurrent race regression test for same-second usage aggregation.

Root cause

The previous recordUsage conflict fallback read the existing row and then wrote quantity + newQuantity from a stale value. When two concurrent calls arrived in the same second, both could read the same pre-update quantity and overwrite each other, causing a lost increment.

Changes made

1. Added JSDoc to the SaveState transition model and the public hook contract in useCustomizationStudio.
2. Documented the debounce timing and cancellation behavior, plus the reason the autosave posts the latest config snapshot directly.
3. Replaced the race-prone fallback with an atomic increment_usage_record_quantity RPC and kept the uniqueness guard in place.
4. Added the migration and a concurrent race regression test covering multiple same-second calls with the same idempotency key.

Validation

This change was implemented without broad test execution, per the requested scope.
EOF

closes #1008
closes #1139

[drips-wave]

@darcszn Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits