/// UPGRADE API USAGE GUIDE
/// 
/// The Upgrade system allows you to modify ball effect parameters at runtime.
/// This is perfect for progression systems, difficulty scaling, or power-ups.
/// 
/// HOW IT WORKS:
/// 1. GameManager holds an UpgradeState that tracks all active upgrades
/// 2. When a ball is assigned a random effect, the UpgradeManager applies active upgrades
/// 3. Upgraded definitions are created as runtime copies - originals are never modified
/// 4. Each ball spawned with upgrades active will have those upgrades applied
/// 
/// ========================================
/// BASIC USAGE EXAMPLES
/// ========================================
/// 
/// // Increase explosive radius by 0.5 units
/// GameManager.Instance.UpgradeExplosiveRadius(0.5f);
/// 
/// // Double the explosive damage (1.0 = no change, 2.0 = double)
/// GameManager.Instance.UpgradeExplosiveDamage(2.0f);
/// 
/// // Add 15 degrees to split angle
/// GameManager.Instance.UpgradeSplitAngle(15f);
/// 
/// // Increase split projectile speed by 50%
/// GameManager.Instance.UpgradeSplitSpeed(1.5f);
/// 
/// // Double split projectile damage
/// GameManager.Instance.UpgradeSplitDamage(2.0f);
/// 
/// // Add 2 extra piercing hits
/// GameManager.Instance.UpgradePiercingHits(2);
/// 
/// // Increase homing turn rate by 50%
/// GameManager.Instance.UpgradeHomingTurnRate(1.5f);
/// 
/// // Triple teleport distance
/// GameManager.Instance.UpgradeTeleportDistance(3.0f);
/// 
/// // Reset all upgrades back to defaults
/// GameManager.Instance.ResetAllUpgrades();
/// 
/// // Get current upgrade state (for UI display or debugging)
/// UpgradeState state = GameManager.Instance.GetUpgradeState();
/// 
/// ========================================
/// UPGRADE STACKING
/// ========================================
/// 
/// Additive upgrades (radius, angle, hits) stack by addition:
/// - UpgradeExplosiveRadius(0.5f) called twice = +1.0 total
/// 
/// Multiplicative upgrades (damage, speed, turn rate, distance) stack by multiplication:
/// - UpgradeSplitSpeed(1.5f) called twice = 1.5 * 1.5 = 2.25x total
/// 
/// ========================================
/// UPGRADE SCOPES
/// ========================================
/// 
/// Explosive Effect Upgrades:
///   - ExplosiveRadius / ExplosiveRadiusBonus
///   - ExplosiveDamage / ExplosiveDamageMultiplier
/// 
/// Triple Split Effect Upgrades:
///   - SplitAngle / SplitAngleBonus
///   - SplitSpeed / SplitSpeedMultiplier
///   - SplitDamage / SplitDamageMultiplier
/// 
/// Piercing Effect Upgrades:
///   - PiercingHits / PiercingHitsBonus
/// 
/// Homing Effect Upgrades:
///   - HomingTurnRate / HomingTurnRateMultiplier
/// 
/// Teleport Effect Upgrades:
///   - TeleportDistance / TeleportDistanceMultiplier
/// 
/// ========================================
/// PRACTICAL PROGRESSION EXAMPLE
/// ========================================
/// 
/// public class ProgressionManager : MonoBehaviour
/// {
///     private int level = 1;
/// 
///     public void ProgressToNextLevel()
///     {
///         level++;
/// 
///         // Scale all upgrades by level
///         GameManager.Instance.UpgradeExplosiveRadius(level * 0.1f);
///         GameManager.Instance.UpgradeExplosiveDamage(1.0f + (level * 0.1f));
///         GameManager.Instance.UpgradeSplitSpeed(1.0f + (level * 0.05f));
///         GameManager.Instance.UpgradePiercingHits(level);
///         GameManager.Instance.UpgradeHomingTurnRate(1.0f + (level * 0.1f));
/// 
///         Debug.Log($"Level {level} upgrades applied!");
///     }
/// }
/// 
/// ========================================
/// IMPLEMENTATION DETAILS
/// ========================================
/// 
/// UpgradeState.cs:
/// - Tracks all upgrade values (both additive and multiplicative)
/// - ResetAll() method returns to defaults
/// - ToString() provides debug output
/// 
/// UpgradeManager.cs (Static):
/// - ApplyUpgrades(definition, upgrades) creates modified copies of definitions
/// - Each effect type has its own upgrade application method
/// - Never modifies original ScriptableObject assets - creates runtime copies only
/// - Safely handles null inputs
/// 
/// GameManager.cs Changes:
/// - Added _upgrades field initialized in Awake()
/// - Modified GetRandomEffect() to apply upgrades via UpgradeManager
/// - Added public methods for each upgrade type
/// - GetUpgradeState() for external inspection
/// - All upgrade methods emit Debug.Log for testing
/// 
/// ========================================
/// NOTES FOR DEVELOPERS
/// ========================================
/// 
/// • Upgrades persist across ball respawns - they apply to all future balls
/// • Upgrade application happens in GetRandomEffect(), called when:
///   - InitializeBallQueue() (initial 5 balls)
///   - InitializeBallQueue() in level restart
///   - Automatically on each new ball from queue
/// • Multipliers use "x" notation (1.5x = 50% increase, 2.0x = 100% increase)
/// • Bonus values are added directly (0.5 units, 15 degrees, 2 hits)
/// • Created upgraded definitions are temporary runtime objects
///   - They don't persist to disk
///   - New definitions recreated each time GetRandomEffect() is called
/// • Safe to call multiple times - values accumulate appropriately
///
/// ========================================
/// DEBUG OUTPUT
/// ========================================
/// 
/// Each upgrade method emits a Debug.Log showing the change and new total.
/// Enable Debug.Log in the Console to see progression:
/// 
/// Example console output:
/// -  Upgraded Explosive Radius: +0.5 (Total: +0.5)
/// -  Upgraded Explosive Damage: x2 (Total: x2.00)
/// -  Upgraded Split Speed: x1.5 (Total: x2.25)
/// -  All upgrades reset to default values.
///