Refactor/z value constants (#6651)

* feat(z-values): add centralized Z-value constants infrastructure

Magic numbers scattered across the codebase make Z-value layering
hard to understand and maintain. Centralizing them provides:
- Self-documenting layer hierarchy
- Validation utilities for development
- Single source of truth for Z-value ranges

Two-tier header design:
- z_value_layer_manager.h: Foundation with constants and validation
- z_values.h: User-facing namespace with semantic constants

* refactor(z-values): replace magic Z-value numbers with ZValues constants

Magic numbers like 2000000007 are impossible to understand without
context. Named constants (ZValues::DRAG_ITEM) are self-documenting.

This intentionally renumbers overlay Z-values to use a cleaner offset
sequence. The relative stacking order is preserved, which is what
matters for correct rendering.

Each consumer now includes z_values.h and uses semantic constants
instead of magic numbers.

* refactor(z-values): removed redundant inline with contexpr, Updated doc, magic numbers removed from TableZone.

cockatrice/src/game/z_values.h

@@ -0,0 +1,83 @@
+#ifndef Z_VALUES_H
+#define Z_VALUES_H
+
+#include "z_value_layer_manager.h"
+
+/**
+ * @file z_values.h
+ * @ingroup GameGraphics
+ * @brief Centralized Z-value constants for rendering layer order.
+ *
+ * Z-values in Qt determine stacking order. Higher values render on top.
+ * These constants define the visual layering hierarchy for the game scene.
+ *
+ * ## Layer Architecture
+ *
+ * See z_value_layer_manager.h for detailed documentation on the three-layer
+ * architecture (Zone, Card, Overlay) and the rationale for Z-value choices.
+ *
+ * ## Quick Reference
+ *
+ * | Layer    | Z-Value Range    | Purpose                           |
+ * |----------|------------------|-----------------------------------|
+ * | Zone     | 0.5 - 1.0        | Zone backgrounds, containers      |
+ * | Card     | 1.0 - 40,000,000 | Cards on table (position-based)   |
+ * | Overlay  | 2,000,000,000+   | UI elements above all cards       |
+ */
+
+namespace ZValues
+{
+
+// Expose base for callers that need it
+constexpr qreal OVERLAY_BASE = ZValueLayerManager::OVERLAY_BASE;
+
+// Overlay layer Z-values for items that should appear above normal cards
+constexpr qreal HOVERED_CARD = ZValueLayerManager::overlayZValue(1.0);
+constexpr qreal ARROWS = ZValueLayerManager::overlayZValue(3.0);
+constexpr qreal ZONE_VIEW_WIDGET = ZValueLayerManager::overlayZValue(4.0);
+constexpr qreal DRAG_ITEM = ZValueLayerManager::overlayZValue(5.0);
+constexpr qreal DRAG_ITEM_CHILD = ZValueLayerManager::overlayZValue(6.0);
+constexpr qreal TOP_UI = ZValueLayerManager::overlayZValue(7.0);
+
+/**
+ * @brief Compute Z-value for child drag items based on hotspot position.
+ *
+ * When dragging multiple cards together, each child card needs a unique Z-value
+ * to prevent Z-fighting (flickering/flashing). The Z-values are derived from
+ * their position when grabbed to conserve original stacking. The formula encodes
+ * 2D coordinates into a single value where X has higher weight, ensuring
+ * deterministic visual stacking.
+ *
+ * @param hotSpotX The X coordinate of the grab position
+ * @param hotSpotY The Y coordinate of the grab position
+ * @return Unique Z-value for the child drag item
+ */
+[[nodiscard]] constexpr qreal childDragZValue(qreal hotSpotX, qreal hotSpotY)
+{
+    return DRAG_ITEM_CHILD + hotSpotX * 1000000 + hotSpotY * 1000 + 1000;
+}
+
+/**
+ * @brief Compute Z-value for cards on the table zone based on position.
+ *
+ * Cards lower on the table (higher Y) render above cards higher up,
+ * and cards to the right (higher X) render above cards to the left.
+ * This creates natural visual stacking for overlapping cards.
+ *
+ * @param x The X coordinate of the card position
+ * @param y The Y coordinate of the card position
+ * @return Z-value for the card's table position
+ */
+[[nodiscard]] constexpr qreal tableCardZValue(qreal x, qreal y)
+{
+    constexpr qreal CARD_HEIGHT_FOR_Z = 102.0;
+    return (y + CARD_HEIGHT_FOR_Z) * 100000.0 + (x + 1) * 100.0;
+}
+
+// Card layering (general architecture, not command-zone specific)
+constexpr qreal CARD_BASE = 1.0;
+constexpr qreal CARD_MAX = ZValueLayerManager::CARD_Z_VALUE_MAX;
+
+} // namespace ZValues
+
+#endif // Z_VALUES_H