Refactor, cleanup code and add documentaiton

Assets/Scripts/CardSystem/StateMachine/States/CardEnlargedLegendaryRepeatState.cs

@@ -0,0 +1,53 @@
+// filepath: Assets/Scripts/UI/CardSystem/StateMachine/States/CardEnlargedLegendaryRepeatState.cs
+using Core;
+using Core.SaveLoad;
+using UnityEngine;
+using AppleHills.Core.Settings;
+
+namespace UI.CardSystem.StateMachine.States
+{
+    /// <summary>
+    /// Enlarged state specifically for Legendary rarity presentation after an upgrade.
+    /// Shows the legendary card enlarged and awaits a click to shrink back to revealed state.
+    /// </summary>
+    public class CardEnlargedLegendaryRepeatState : AppleState, ICardClickHandler
+    {
+        private CardContext _context;
+        
+        private void Awake()
+        {
+            _context = GetComponentInParent<CardContext>();
+        }
+        
+        public override void OnEnterState()
+        {
+            // Ensure card front is visible and facing camera
+            if (_context.CardDisplay != null)
+            {
+                _context.CardDisplay.gameObject.SetActive(true);
+                _context.CardDisplay.transform.localRotation = Quaternion.Euler(0, 0, 0);
+            }
+            
+            // Card is already enlarged from EnlargedRepeatState, so no need to enlarge again
+            // Just await click to dismiss
+            
+            Logging.Debug($"[CardEnlargedLegendaryRepeatState] Legendary card enlarged: {_context.CardData?.Name}");
+        }
+        
+        public void OnCardClicked(CardContext context)
+        {
+            // Click to shrink to original scale and go to revealed state
+            if (context.Animator != null)
+            {
+                context.Animator.PlayShrink(context.OriginalScale, onComplete: () =>
+                {
+                    context.StateMachine.ChangeState("RevealedState");
+                });
+            }
+            else
+            {
+                context.StateMachine.ChangeState("RevealedState");
+            }
+        }
+    }
+}