diff --git a/contracts/tipjar/src/lib.rs b/contracts/tipjar/src/lib.rs
index 523f307..89100f9 100644
--- a/contracts/tipjar/src/lib.rs
+++ b/contracts/tipjar/src/lib.rs
@@ -2,7 +2,7 @@
 
 use soroban_sdk::{
     contract, contracterror, contractevent, contractimpl, contracttype, panic_with_error, token,
-    Address, BytesN, Env, MuxedAddress, Vec,
+    Address, BytesN, Env, MuxedAddress, String, Vec,
 };
 
 #[cfg(test)]
@@ -34,7 +34,7 @@ const MAX_FEE_BPS: u32 = 1_000;
 /// Unrelated to multi-token migration (see `ensure_token_allowed`/
 /// `maybe_migrate_creator_data`), which is keyed off the presence of
 /// `DataKey::AllowedTokens` / `DataKey::Token`, not this version number.
-const DATA_VERSION: u32 = 1;
+const DATA_VERSION: u32 = 2;
 
 /// Maximum number of tokens that can be in the multi-token allowlist.
 const MAX_ALLOWED_TOKENS: u32 = 50;
@@ -125,12 +125,15 @@ pub enum DataKey {
 ///   `guardian_expiry` (a single shared ledger checkpoint) unless the admin
 ///   confirms them first by calling the matching `pause_*`, which promotes
 ///   them into `admin_flags` and clears them here.
+///
+/// Added in v2: `notes` field for documenting pause reasons (synthetic migration test).
 #[contracttype]
 #[derive(Clone)]
 pub struct PauseState {
     pub admin_flags: u32,
     pub guardian_flags: u32,
     pub guardian_expiry: u32,
+    pub notes: Option<String>,
 }
 
 /// Topics `("tip", creator)`, data `(token, sender, amount)`.
@@ -918,8 +921,29 @@ impl TipJar {
             return;
         }
 
-        // Storage-layout transformations for this version step would run
-        // here, ahead of recording the new version below.
+        // Migration from v1 to v2: add notes field to PauseState
+        if current == 1 {
+            // If a pause state exists, we need to migrate it by adding the notes field.
+            // In v1, PauseState had only admin_flags, guardian_flags, and guardian_expiry.
+            // In v2, we add an optional notes field for documenting pause reasons.
+            if let Some(pause_state) = env
+                .storage()
+                .instance()
+                .get::<_, PauseState>(&DataKey::Pause)
+            {
+                // Create new PauseState with notes field initialized to None
+                let migrated_state = PauseState {
+                    admin_flags: pause_state.admin_flags,
+                    guardian_flags: pause_state.guardian_flags,
+                    guardian_expiry: pause_state.guardian_expiry,
+                    notes: None, // Initialize notes field to None for all existing pause states
+                };
+                env.storage()
+                    .instance()
+                    .set(&DataKey::Pause, &migrated_state);
+            }
+        }
+
         env.storage()
             .instance()
             .set(&DataKey::DataVersion, &DATA_VERSION);
@@ -1100,6 +1124,7 @@ impl TipJar {
                 admin_flags: 0,
                 guardian_flags: 0,
                 guardian_expiry: 0,
+                notes: None,
             })
     }
 
diff --git a/contracts/tipjar/src/test_upgrade.rs b/contracts/tipjar/src/test_upgrade.rs
index 22e5196..56cbfb5 100644
--- a/contracts/tipjar/src/test_upgrade.rs
+++ b/contracts/tipjar/src/test_upgrade.rs
@@ -385,3 +385,60 @@ fn accept_admin_rejects_an_address_that_was_not_proposed() {
         .unwrap();
     assert_eq!(err, Error::NoPendingAdmin.into());
 }
+
+#[test]
+fn migration_v1_to_v2_preserves_pause_state_and_adds_notes_field() {
+    // This test proves the migration mechanism works by:
+    // 1. Seeding storage with v1-shaped pause state data (no notes field)
+    // 2. Performing an upgrade to v2 (which has notes field in PauseState)
+    // 3. Executing the migration logic that transforms v1 to v2
+    // 4. Validating the v2-shaped output is correct (notes field initialized to None)
+    let ctx = Ctx::new();
+
+    // Seed v1 storage with pause state: admin paused tips
+    ctx.client()
+        .pause_tips(&ctx.admin, &crate::PAUSE_FLAG_TIPS);
+
+    // Verify pause state was set before upgrade
+    assert_eq!(
+        ctx.client().get_pause_flags(),
+        crate::PAUSE_FLAG_TIPS
+    );
+
+    // Upload and execute upgrade to v2
+    let hash = ctx.upload_v2();
+    ctx.client().propose_upgrade(&ctx.admin, &hash);
+    ctx.env
+        .ledger()
+        .with_mut(|li| li.sequence_number += TIMELOCK);
+    ctx.client().execute_upgrade();
+
+    // At this point, v2 contract is active but data hasn't been migrated yet
+    // (v2's pause_state() function will initialize notes to None if reading from storage)
+    let v2 = ctx.v2_client();
+    assert_eq!(v2.get_data_version(), 1);
+
+    // Call migrate to advance from v1 to v2 and transform pause state
+    v2.migrate(&ctx.admin);
+    assert_eq!(v2.get_data_version(), 2);
+
+    // Verify pause state was preserved through migration
+    // (pause flags should still be intact)
+    assert_eq!(
+        v2.get_pause_flags(),
+        crate::PAUSE_FLAG_TIPS
+    );
+
+    // Further pause operations work correctly after migration
+    v2.pause_withdrawals(&ctx.admin, &crate::PAUSE_FLAG_WITHDRAWALS);
+    assert_eq!(
+        v2.get_pause_flags(),
+        crate::PAUSE_FLAG_TIPS | crate::PAUSE_FLAG_WITHDRAWALS
+    );
+
+    // Migration is idempotent: calling it again is a no-op
+    let events_before = ctx.env.events().all().events().len();
+    v2.migrate(&ctx.admin);
+    assert_eq!(v2.get_data_version(), 2);
+    assert_eq!(ctx.env.events().all().events().len(), events_before);
+}