docs(entities): Document Warehouse/Product duplications and domain separation

- Add deprecation notice to inventory/warehouse.entity.ts
  - Duplicated with warehouses/warehouse.entity.ts (same table)
  - Plan unification in warehouses module with all fields and relations

- Document that Product entities are NOT duplicates
  - products.products: Commerce/retail focused (SAT, pricing, dimensions)
  - inventory.products: Warehouse management focused (Odoo-style, valuation)
  - Intentionally separate by domain

src/modules/inventory/entities/product.entity.ts

@@ -10,6 +10,23 @@ import {
 import { StockQuant } from './stock-quant.entity.js';
 import { Lot } from './lot.entity.js';
 
+/**
+ * Inventory Product Entity (schema: inventory.products)
+ *
+ * NOTE: This is NOT a duplicate of products/entities/product.entity.ts
+ *
+ * Key differences:
+ * - This entity: inventory.products - Warehouse/stock management focused (Odoo-style)
+ *   - Has: valuationMethod, tracking (lot/serial), isStorable, StockQuant/Lot relations
+ *   - Used by: Inventory module for stock tracking, valuation, picking operations
+ *
+ * - Products entity: products.products - Commerce/retail focused
+ *   - Has: SAT codes, tax rates, detailed dimensions, min/max stock, reorder points
+ *   - Used by: Sales, purchases, invoicing
+ *
+ * These are intentionally separate by domain. A product in the products schema
+ * may reference an inventory product for stock tracking purposes.
+ */
 export enum ProductType {
   STORABLE = 'storable',
   CONSUMABLE = 'consumable',

src/modules/inventory/entities/warehouse.entity.ts

@@ -12,6 +12,17 @@ import {
 import { Company } from '../../auth/entities/company.entity.js';
 import { Location } from './location.entity.js';
 
+/**
+ * @deprecated This entity is duplicated with warehouses/entities/warehouse.entity.ts
+ * Both map to inventory.warehouses table but have different column definitions.
+ *
+ * PLANNED UNIFICATION:
+ * - The warehouses module version has more comprehensive fields (address, capacity, settings)
+ * - This version has Company and Location relations
+ * - Future: Merge into single entity in warehouses module with all fields and relations
+ *
+ * For new code, prefer using: import { Warehouse } from '@modules/warehouses/entities'
+ */
 @Entity({ schema: 'inventory', name: 'warehouses' })
 @Index('idx_warehouses_tenant_id', ['tenantId'])
 @Index('idx_warehouses_company_id', ['companyId'])

src/modules/products/entities/product.entity.ts

@@ -11,6 +11,24 @@ import {
 } from 'typeorm';
 import { ProductCategory } from './product-category.entity';
 
+/**
+ * Commerce Product Entity (schema: products.products)
+ *
+ * NOTE: This is NOT a duplicate of inventory/entities/product.entity.ts
+ *
+ * Key differences:
+ * - This entity: products.products - Commerce/retail focused
+ *   - Has: SAT codes, tax rates, detailed dimensions, min/max stock, reorder points
+ *   - Used by: Sales, purchases, invoicing, POS
+ *
+ * - Inventory Product: inventory.products - Warehouse/stock management focused (Odoo-style)
+ *   - Has: valuationMethod, tracking (lot/serial), isStorable, StockQuant/Lot relations
+ *   - Used by: Inventory module for stock tracking, valuation, picking operations
+ *
+ * These are intentionally separate by domain. This commerce product entity handles
+ * pricing, tax compliance (SAT/CFDI), and business rules. For physical stock tracking,
+ * use the inventory module's product entity.
+ */
 @Entity({ name: 'products', schema: 'products' })
 export class Product {
   @PrimaryGeneratedColumn('uuid')