documented ORM access api

Also added a quick comment in the Entity class and fixed a mistake in the motivation doc.